home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 039a / uw201.zip / UW_HELP5.HLP < prev    next >
Text File  |  1991-10-07  |  20KB  |  497 lines
  1. `co(4,7);──────────────────────── /// General Macros ────────────────────────────────`co();
  2.     These are some macros (defined in uw.h) that are for general use
  3.     in your programs!
  4.  
  5. `co(10,1);/// hibyte`co();
  6.     #define hibyte(c)              (uchar) ((c) >> 8)
  7.     Yields the most significant byte of integer c.
  8.  
  9. `co(10,1);/// lobyte`co();
  10.     #define lobyte(c)              (uchar) ((c) & 0x00ff)
  11.     Yields the least significant byte of integer c.
  12.  
  13. `co(10,1);/// lower`co();
  14.     #define lower (x, y)         (x < y) ? x : y
  15.     Yields the lesser of the values x and y.
  16.  
  17. `co(10,1);/// range`co();
  18.     #define range(l,b,h)         ((((b) >= (l)) && ((b) <= (h))))
  19.     Yields a 1 if b is between l and h inclusive.
  20.  
  21. `co(10,1);/// swap`co();
  22.     #define swap(a,b,c)          ((c) = (a), (a) = (b), (b) = (c))
  23.     Swaps the values a and b utilizing a temporary c.
  24.  
  25. `co(10,1);/// upper`co();
  26.     #define upper (x, y)         (x > y) ? x : y
  27.   Yields the greater of the values x and y.
  28.  
  29. `co(4,7);──────────────────────── /// Window Macros ─────────────────────────────────`co();
  30.     These are some useful window macros (defined in uw.h) that will
  31.     make manipulation of windows a little easier.
  32.  
  33. `co(10,1);/// cls`co();
  34.     #define cls()                                 (setmem(Screen, V_cols * V_rows * 2, 0))
  35.     Clears the entire screen to black.
  36.  
  37. `co(10,1);/// mv_cs`co();
  38.     #define mv_cs(c,r,wnp)                ((wnp)->csr_x = (c), (wnp)->csr_y = (r))
  39.     Moves the "soft" cursor in window wnp to the column and row c and r.
  40.     
  41. `co(10,1);/// wn_att`co();
  42.     #define wn_att(a,wnp)                 ((wnp)->att = (a))
  43.     Sets the window attribute in wnp to the value a.
  44.  
  45. `co(10,1);/// wn_bdratt`co();
  46.     #define wn_bdratt(a,wnp)            ((wnp)->bdr_att = (a))
  47.     Sets the window boder attribute in wnp to the value a.    This is
  48.     the complement to the wn_att macro.
  49.     
  50. `co(10,1);/// wn_bdr_color`co();
  51.     #define wn_bdr_color(f,b,wnp) ((wnp)->bdr_att = ((b) << 4) | (f))
  52.     Sets the border foreground and background colors in window wnp.  This
  53.     is the complement to the wn_color macro.
  54.  
  55. `co(10,1);/// wn_color`co();
  56.     #define wn_color(f,b,wnp)         ((wnp)->att = ((b) << 4) | (f))
  57.     Sets the foreground and background colors in window wnp.    This is
  58.     done by setting the window attribute accordingly.
  59.     
  60. `co(10,1);/// wn_name`co();
  61.     #define wn_name(n, wnp)             ((wnp)->name = (n))
  62.     Sets the name at the top of window wnp to the string n.
  63.  
  64. `co(10,1);/// wn_name_loc`co();
  65.     #define wn_name_loc(l, wnp)     ((wnp)->name_loc = (l))
  66.     Sets the location of the name in window wnp to left, right, or
  67.     centered.
  68.  
  69. `co(10,1);/// wn_read`co();
  70.     #define wn_read( wnp )                (wn_io( IN, BUFF, (wnp)))
  71.     Pulls what is actually on the screen under the window into the
  72.     window itself!    This is like wn_save, but instead of pulling the
  73.     area under the window into the save/restore buffer, it pulls it
  74.     into the window.
  75.  
  76. `co(10,1);/// wn_restore`co();
  77.     #define wn_restore( wnp )         (wn_io(OUT, SAVE, (wnp)))
  78.     Restores the area saved (by the macro wn_save) under the window wnp.
  79.     
  80. `co(10,1);/// wn_rfsh`co();
  81.     #define wn_rfsh( wnp )                (wn_io(OUT, BUFF, (wnp)))
  82.     Redraws (refreshes) the window wnp.
  83.  
  84. `co(10,1);/// wn_save`co();
  85.     #define wn_save( wnp )                (wn_io( IN, SAVE, (wnp)))
  86.     Saves the area under the window wnp to the window save area for later
  87.     restoration.
  88.  
  89. `co(4,7);───────────────────────── /// Font/EGA Control ──────────────────────────────`co();
  90.  
  91. ┌──────────────────────────────────────────────────────────────────────────┐    
  92. │          `keyword(encode_color,/// encode_color);                      `keyword(decode_color,/// decode_color);                  │
  93. │          `keyword(load_font,/// load_font);                         `keyword(save_font,/// save_font);                     │
  94. │          `keyword(install_font,/// install_font);                      `keyword(get_font_info,/// get_font_info);                 │
  95. │          `keyword(blink_enable,/// blink_enable);                      `keyword(replicate_enable,/// replicate_enable);              │
  96. │          `keyword(set_block_ab,/// set_block_ab);                      `keyword(rom8x8,/// rom8x8);                        │
  97. │          `keyword(rom8x14,/// rom8x14);                           `keyword(rom8x16,/// rom8x16);                       │
  98. │          `keyword(read_palette,/// read_palette);                      `keyword(read_palette_all,/// read_palette_all);              │
  99. │          `keyword(write_palette,/// write_palette);                     `keyword(write_palette_all,/// write_palette_all);             │
  100. └──────────────────────────────────────────────────────────────────────────┘
  101.  
  102. These functions are specific to EGA/VGA boards and are advanced features.
  103. We do not attempt to explain all the details and quirks of the EGA/VGA video
  104. subsystems.  We recommend you have some reference material detailing the
  105. EGA/VGA video system if our descriptions are not clear or complete enough.
  106.  
  107. It is not possible to read the palette registers on an EGA board.  We
  108. resolve this deficiency by keeping a "shadow" palette that is initialized
  109. to the standard EGA values.  When you read/write the palette registers,
  110. you are also accessing this "shadow" area.
  111.  
  112. `co(10,1);/// encode_color`co();   `keyword(source,[UW_FONT.C]~encode_color);
  113.   This routine takes the individual Red, Green, and Blue color components 
  114.   and encodes them into a format suitable for the EGA/VGA palette registers,
  115.   returning this value as an integer.
  116.                        see also `keyword(decode_color,/// decode_color);
  117.  
  118. Prototype:
  119. void encode_color(int r, int g, int b);
  120.  
  121. Parameters:
  122. `co(11,1);    int r, g, b`co();
  123.         Integers containing each color component.
  124.  
  125. Usage:
  126.     int color, r = 2, g = 3, b = 1;
  127.     ...
  128.     color = encode_color( r, g, b );
  129.  
  130. `co(10,1);/// decode_color`co();   `keyword(source,[UW_FONT.C]~decode_color);
  131.   This routine takes an EGA/VGA color encoded value as it would be stored
  132.   in a palette register and returns the individual Red, Green, and Blue
  133.   components.
  134.                        see also `keyword(encode_color,/// encode_color);
  135.  
  136. Prototype:
  137. void decode_color(int color, int *r, int *g, int *b);
  138.  
  139. Parameters:
  140. `co(11,1);    int color;`co();
  141.         The EGA/VGA encoded color value.
  142. `co(11,1);    int *r, *g, *b`co();
  143.         Integer pointers to store each color component.
  144.  
  145. Usage:
  146.     int color, r, g, b;
  147.     color = random(64);
  148.     ...
  149.     decode_color( color, &r, &g, &b );
  150.  
  151. `co(10,1);/// load_font`co();   `keyword(source,[UW_FONT.C]~load_font);
  152.   This routine loads a font pattern file into memory. The fonts are stored
  153.   int raw format, with no header information residing in the file.  As an
  154.   example, let's say we have a file containing 256 8x14 characters.  The
  155.   first characters' pattern is contained in the first 14 bytes, the second
  156.   in bytes 15-28, and so on.  This is the complement of save_font.  Upon a
  157.   successful load, the function will return the number of scan lines that
  158.   are in each character, or 0 upon failure.
  159.                             see also `keyword(save_font,/// save_font);
  160. Prototype:
  161. int load_font( uchar *font, char *fname );
  162.  
  163. Parameters:
  164. `co(11,1);    uchar *font;`co();
  165.         A pointer to an area large enough to hold the font pattern data.
  166. `co(11,1);    char  *fname;`co();
  167.         A pointer to the filename that contains the font pattern data.
  168.  
  169. Usage:
  170.     uchar Font8x14[256][14];                                            /* global array */
  171.     int Scan_lines;
  172.     ...
  173.     Scan_lines = load_font( Font8x14, "8x14icon.fnt");
  174.  
  175. `co(10,1);/// save_font`co();   `keyword(source,[UW_FONT.C]~save_font);
  176.   This routine saves a font pattern from memory into a file.
  177.   This is the complement of load_font.
  178.                             see also `keyword(load_font,/// load_font);
  179.   
  180. Prototype:
  181. int save_font( uchar *font, char *fname, int scan_lines );
  182.  
  183. Parameters:
  184. `co(11,1);    uchar *font;`co();
  185.         A pointer to an area containing the font pattern data.
  186. `co(11,1);    char  *fname;`co();
  187.         A pointer to the filename to which to save the font data.
  188. `co(11,1);    int   scan_lines;`co();
  189.         The number of scan_lines the font contains (typically 8/14/16).
  190.  
  191. Usage:
  192.     uchar Font8x14[256][14];                                            /* global array */
  193.     ...
  194.     save_font( Font8x14, "8x14ICON.FNT", 14 );
  195.  
  196. `co(10,1);/// install_font`co();   `keyword(source,[UW_FONT.C]~install_font);
  197.   This routine installs a font loaded into memory, into the EGA/VGA bios
  198.   area.  Two sets of 256 characters can be resident at one time.  "block"
  199.   determines which set to install this font as.  If "setmode" is non-zero,
  200.   the video mode will be reset.
  201.   
  202. Prototype:
  203. void install_font(uchar *font, int block, int offset, int cnt,
  204.     int scan_lines, int setmode );
  205.  
  206. Parameters:
  207. `co(11,1);    uchar *font;`co();
  208.         A pointer to an area containing the font pattern data.
  209. `co(11,1);    int   block;`co();
  210.         The character set in which to load this font. (0 or 1).
  211. `co(11,1);    int   offset;`co();
  212.         The character offset to load the new font data, typically 0.
  213. `co(11,1);    int   cnt;`co();
  214.         The number of characters to install (max 256).
  215. `co(11,1);    int   scan_lines;`co();
  216.         The number of scan_lines the font contains (typically 8/14/16).
  217. `co(11,1);    int   set_mode;`co();
  218.         If non-zero, the video mode will be reset.
  219.  
  220. Usage:
  221.     uchar Font8x14[256][14];                                            /* global array */
  222.     ...
  223.     load_font( Font8x14, "8x14icon.fnt", 256, 14 );
  224.   install_font( Font8x14, 1, 0, 256, 14, 0 );
  225.  
  226. `co(10,1);/// get_font_info`co();   `keyword(source,[UW_FONT.C]~get_font_info);
  227.   This routine returns the address, scan_lines, and video character rows 
  228.   of the current font.
  229.     
  230. Prototype:
  231. uchar far *get_font_info( int type, int *scan_lines, int *rows );
  232.  
  233. Parameters:
  234. `co(11,1);    int   type;`co();
  235.     2 - get address of ROM 8x14 font
  236.     3 - get address of ROM 8x8 font
  237.     4 - get address of second half of ROM 8x8 font
  238.     5 - get address of ROM 9x14 alternate font
  239.     6 - get address of ROM 8x16 font
  240.     7 - get address of ROM 9x16 alternate font
  241. `co(11,1);    int   *scan_lines;`co();
  242.         A pointer to an integer in which to store the number of scan lines in 
  243.     the current font.
  244. `co(11,1);    int   *rows;`co();
  245.         A pointer to an integer in which to store the number of character rows
  246.     for the current screen mode.
  247.  
  248. Usage:
  249.     int scan_lines, rows;
  250.     uchar far  *font;
  251.     ...
  252.     font = get_font_info( 2, &scan_lines, &rows );
  253.  
  254. `co(10,1);/// blink_enable`co();   `keyword(source,[UW_FONT.C]~blink_enable);
  255.   This routine enables/disables blinking on EGA/VGA systems. When the
  256.   blink bit is disabled, all 256 possible color combinations (16 foreground,
  257.   16 background) can be displayed at one time with no blinking.  If enabled,
  258.   those character cells whose background color is 8-15 will blink.
  259.  
  260. Prototype:
  261. void blink_enable(int state);
  262.  
  263. Parameters:
  264. `co(11,1);    int   state;`co();
  265.         1 to enable blink, 0 to disable blink.
  266.  
  267. Usage:
  268.     ...
  269.     blink_enable(1);
  270.  
  271. `co(10,1);/// replicate_enable`co();   `keyword(source,[UW_FONT.C]~replicate_enable);
  272.   This routine enables/disables 9th pixel replication for the 32 characters
  273.   0xC0 - 0xDF on EGA/VGA boards.  The use of this function depends on the
  274.   video card in use.  Some cards (especially in monochrome modes) use a 9
  275.   pixel wide cell, even though the font is only 8 pixels wide. This usually
  276.   causes no problem as the hardware hides this from us.  However, when 
  277.   performing line drawing or other operations where characters must join,
  278.   a gap may exist.  The hardware is capable of replicating the 8th bit
  279.   into the 9th bit to allow for continuous characters. The hardware only
  280.   does this for the line drawing character block 0xC0 - 0xDF. In short, if
  281.   you modify your own fonts and create new borders, lines, etc. that need to
  282.   be continuous, it is recommended that you store these characters in this 
  283.   area and enable replication.  No other character cells will be affected.
  284.  
  285. Prototype:
  286. void replicate_enable(int state);
  287.  
  288. Parameters:
  289. `co(11,1);    int   state;`co();
  290.         1 to enable 9th pixel replication, 0 to disable replication.
  291.  
  292. Usage:
  293.     ...
  294.     replicate_enable(1);
  295.  
  296. `co(10,1);/// set_block_ab`co();   `keyword(source,[UW_FONT.C]~set_block_ab);
  297.   This routine sets the two possible active fonts as primary secondary.
  298.   Both blocks can be set to the same mode.  For example, if we load
  299.   a standard 8x14 font into block 0, and an 8x14 icon font into block 1,
  300.   we might say "set_block_ab(0,1)".  This sets the 8x14 as the primary 
  301.   font and the icon font as secondary. (Displayed if the background 
  302.   is 8-15).  If "set_block_ab(1,0)" is called, the two fonts will be
  303.   effectively switched.  "set_block_ab(0,0)" will always display the
  304.   8x14 font regardless of attribute settings.
  305.  
  306. Prototype:
  307. void set_block_ab(int a, int b);
  308.  
  309. Parameters:
  310. `co(11,1);    int   a;`co();
  311.         0 - set font 0 as primary font, 1 - set font 0 as alternate font.
  312. `co(11,1);    int   b;`co();
  313.         0 - set font 1 as primary font, 1 - set font 1 as alternate font.
  314.  
  315. Usage:
  316.     ...
  317.     load_font( Font8x14, "8x14.fnt", 256, 14 );
  318.   install_font( Font8x14, 0, 256, 14, 0 );
  319.     load_font( Font8x14, "8x14icon.fnt", 256, 14 );
  320.   install_font( Font8x14, 1, 256, 14, 0 );
  321.     set_block_ab(0,1);                    /* 8x14 - block 0, 8x14icon block 1 */
  322.  
  323. `co(10,1);/// rom8x8`co();   `keyword(source,[UW_FONT.C]~rom8x8);
  324.   This routine loads the video BIOS 8x8 font into the desired block
  325.   and optionally resets the video mode. (EGA/VGA)
  326.  
  327. Prototype:
  328. void rom8x8(int block, int setmode);
  329.  
  330. Parameters:
  331. `co(11,1);    int   block;`co();
  332.         0 - load font into block 0, 1 - load font into block 1.
  333. `co(11,1);    int   setmode;`co();
  334.         0 - do not reset video mode. 1- set video mode.
  335.  
  336. Usage:
  337.     ...
  338.     rom8x8(0,1);                                                /* load as primary, reset video mode  */
  339.  
  340. `co(10,1);/// rom8x14`co();   `keyword(source,[UW_FONT.C]~rom8x14);
  341.   This routine loads the video BIOS 8x14 font into the desired block
  342.   and optionally resets the video mode. (EGA/VGA)
  343.  
  344. Prototype:
  345. void rom8x14(int block, int setmode);
  346.  
  347. Parameters:
  348. `co(11,1);    int   block;`co();
  349.         0 - load font into block 0, 1 - load font into block 1.
  350. `co(11,1);    int   setmode;`co();
  351.         0 - do not reset video mode. 1- set video mode.
  352.  
  353. Usage:
  354.     ...
  355.     rom8x14(1,0);                                                /* load as alternate, don't reset     */
  356.  
  357. `co(10,1);/// rom8x16`co();   `keyword(source,[UW_FONT.C]~rom8x16);
  358.   This routine loads the video BIOS 8x16 font into the desired block
  359.   and optionally resets the video mode. (VGA only)
  360.  
  361. Prototype:
  362. void rom8x16(int block, int setmode);
  363.  
  364. Parameters:
  365. `co(11,1);    int   block;`co();
  366.         0 - load font into block 0, 1 - load font into block 1.
  367. `co(11,1);    int   setmode;`co();
  368.         0 - do not reset video mode. 1- set video mode.
  369.  
  370. Usage:
  371.     ...
  372.     rom8x16(0,0);                                                /* load as primary, don't reset mode  */
  373.  
  374. `co(10,1);/// read_palette`co();   `keyword(source,[UW_FONT.C]~read_palette);
  375.   This routine reads a single palette register and returns the value.
  376.   To determine the RGB components, see `keyword(decode_color,/// decode_color); above.
  377.  
  378. Prototype:
  379. int read_palette( int pnum );
  380.  
  381. Parameters:
  382. `co(11,1);    int   pnum;`co();
  383.         The color palette index to read (0-15).
  384.  
  385. Usage:
  386.     int color;
  387.     ...
  388.     color = read_palette(6);
  389.  
  390. `co(10,1);/// read_palette_all`co();   `keyword(source,[UW_FONT.C]~read_palette_all);
  391.   This routine reads all 16 palette registers and stores the values into
  392.   the desired area.
  393.  
  394. Prototype:
  395. int read_palette_all( uchar *vals );
  396.  
  397. Parameters:
  398. `co(11,1);    uchar  *vals;`co();
  399.         A pointer to an array (at least 16 bytes) in which to store the values.
  400.  
  401. Usage:
  402.     uchar colors[16];
  403.     ...
  404.     read_palette_all(colors);
  405.  
  406. `co(10,1);/// write_palette`co();   `keyword(source,[UW_FONT.C]~write_palette);
  407.   This routine writes a value to a single palette register. To specify the
  408.   color in RGB components, see `keyword(encode_color,/// encode_color); above.
  409.  
  410. Prototype:
  411. int write_palette( int pnum, uchar val );
  412.  
  413. Parameters:
  414. `co(11,1);    int   pnum;`co();
  415.         The color palette index to write (0-15).
  416. `co(11,1);    uchar val;`co();
  417.         The color palette value.
  418.  
  419. Usage:
  420.     ...
  421.   write_palette(6, encode_color(1,3,2));
  422.  
  423. `co(10,1);/// write_palette_all`co();   `keyword(source,[UW_FONT.C]~write_palette_all);
  424.   This routine writes values to all palette registers.
  425.  
  426. Prototype:
  427. int write_palette_all( uchar *vals );
  428.  
  429. Parameters:
  430. `co(11,1);    uchar *vals;`co();
  431.         The 16 color palette values.
  432.  
  433. Usage:
  434. char palette[16] =
  435. { 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x14,    0x07,
  436.     0x38, 0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f };
  437.     ...
  438.   write_palette_all(palette);
  439.  
  440. `color(RED,LIGHTGRAY);────────────────────────  /// Graphics Support ─────────────────────────────`color();
  441.   UltraWin version 2.0 adds EGA/VGA graphics support.  It does not add
  442.   a graphics library or initilization routines.  You must first have your
  443.   system in either EGA 640x350x16 or VGA 640x480x16 mode.  To tell UltraWin
  444.   that it should draw all text in graphics mode, simply call `keyword(init_uw_graphics,/// init_uw_graphics);.
  445.   See `keyword(g_ch,/// g_ch); for details on graphics output.
  446.  
  447. `co(10,1);/// init_uw_graphics`co();   `keyword(source,[UW_GRAPH.C]~init_uw_graphics);
  448.   This routine initializes UltraWin to support EGA/VGA graphics output.
  449.  
  450. Prototype:
  451. int init_uw_graphics( int xres, int yres, int font_rows,
  452.                       int font_spacing, int seg, int off );
  453.  
  454. Parameters:
  455.   Parameters:
  456. `co(11,1);  int xres, yres`co();   - resolution in pixels for EGA/VGA         
  457. `co(11,1);  int font_rows`co();    - number of scan lines for current font    
  458. `co(11,1);  int font_spacing`co(); - number of scan lines between characters  
  459. `co(11,1);  int seg`co();          - graphics segment (-1 sets default 0xa000)
  460. `co(11,1);  int off`co();          - graphics offset  (-1 sets default 0x0000)
  461.  
  462. Usage:
  463.     ...
  464.     init_uw_graphics( 640, 350, 14, 14, -1, -1 );
  465.  
  466. `co(10,1);/// g_ch`co();   `keyword(source,[UW_GRAPH.C]~g_ch);
  467.   This routine outputs a single character to the graphics screen.  It will
  468.   not normally be called by you.  It is a very important function for those
  469.   of you interested in non-text mode support.  All UltraWin output will go
  470.   through this routine when the graphics flag is set.  This allows you to
  471.   not only use our function, but to write your own to support other graphics
  472.   standards, dumb-terminals, and virtually any non-standard hardware.  Note
  473.   that when the global variable G_opt is set, the output routine will not
  474.   draw if the character is already on the screen in the proper color.
  475.   Also note that this function, along with get_font_info and install_font
  476.   are only compilable under the Borland compilers, Microsoft users can
  477.   link this module into their programs if need be.
  478.   It is very important to understand what happens here.  We simply replace
  479.   output routines - no other graphics support is supported - UltraWin
  480.   works exactly as it does in text mode.  It will not save/restore graphics
  481.   areas under windows - you must do this yourself, if desired.
  482.  
  483. Prototype:
  484. int g_ch( int c, int r, int v );
  485.  
  486. Parameters:
  487.   Parameters:
  488. `co(11,1);    int c;`co(); - col (UltraWin col 0-V_cols - 1, not pixel col)
  489. `co(11,1);  int r;`co(); - row (UltraWin row 0-V_rows - 1, not pixel row)
  490. `co(11,1);  int v;`co(); - character value (0-255)
  491.  
  492. Usage:
  493.     ...
  494.     g_ch(10, 15, 'x');
  495.  
  496. `co(4,7);─ End ──────────────────────────────────────────────────────────────────────`co();`sound(1024,10);
  497.